package net.sf.xoperator.blackboard;

import java.util.Iterator;

import org.openbbs.blackboard.EntryFilter;
import org.openbbs.blackboard.Zone;
import org.openbbs.blackboard.ZoneSelector;

public interface MultiInstanceBlackBoardMemory  {
	
	   /**
		 * Create a new zone in the memory. The zone must not exist.
		 * 
		 * @param zone
		 *            a non-null Zone to create. Implementors may restrict the
		 *            possible Zone implementations.
		 */
	   public void createZone(Zone zone);

	   /**
		 * Remove an existing zone from the memory. All entries in this zone are
		 * also removed.
		 * 
		 * @param zone
		 *            a non-null, existing Zone.
		 */
	   public void dropZone(Zone zone);

	   /**
		 * Check wether a particular zone exists in the memory.
		 * 
		 * @param zone
		 *            a non-null Zone.
		 */
	   public boolean zoneExists(Zone zone);

	   /**
		 * Store a new entry inside a zone of the memory. No entry which is
		 * equal to the specified entry must exist in any zone of the memory.
		 * 
		 * @param zone
		 *            the zone in which the entry should be stored. Implementors
		 *            may place specific constraints on zones. Not null.
		 * @param entry
		 *            the entry to be stored. Implementors may place specific
		 *            constraints on entries, such as that an entry must be
		 *            Serializable. Not null.
		 */
	   public void storeEntry(Zone zone, Object entry);

	   /**
		 * Remove an entry from the memory. An entry which is equal to the
		 * specified entry must exist and will be removed.
		 * 
		 * @param entry
		 *            the entry to be removed.
		 */
	   public void removeEntry(Object entry);

	   /**
		 * Check whether a given entry exists in the memory.
		 * 
		 * @param entry
		 *            a non-null entry.
		 */
	   public boolean entryExists(Object entry);

	   /**
		 * Get the zone in which a particular entry is stored. Returns null if
		 * the entry is not stored in this memory.
		 * 
		 * @param entry
		 *            a non-null entry.
		 */
	   public Zone getZones(Object entry);

	   /**
		 * Get an Iterator over all entries in the memory which reside in a zone
		 * that is machted by the specified {@link ZoneSelector} and is selected
		 * by the specified {@EntryFilter}. If no such entry is found, the
		 * returned Iterator is empty.
		 * 
		 * @param zoneSelector
		 *            a non-null ZoneSelector. Implementors may restrict the
		 *            possible ZoneSelectors to specific implementations.
		 * @param entryFilter
		 *            a non-null EntryFilter. Implementors may restrict the
		 *            possible EntryFilters to specific implementations.
		 */
	   public Iterator<Object> getEntries(ZoneSelector zoneSelector, EntryFilter entryFilter);
	


}
